<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Index API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'docs-index_.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/docs-index_.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/docs-index_.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/docs-index_.html" rel="nofollow" target="_blank">../en/docs-index_.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="docs.html">Document APIs</a></span>
»
<span class="breadcrumb-node">Index API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="docs-replication.html">« Reading and Writing documents</a>
</span>
<span class="next">
<a href="docs-get.html">Get API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="docs-index_"></a>Index API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h2>
</div></div></div>

<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>See <a class="xref" href="removal-of-types.html" title="Removal of mapping types"><em>Removal of mapping types</em></a>.</p>
</div>
</div>
<p>Adds a JSON document to the specified index and makes
it searchable. If the document already exists,
updates the document and increments its version.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-index-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">PUT /&lt;index&gt;/_doc/&lt;_id&gt;</code></p>
<p><code class="literal">POST /&lt;index&gt;/_doc/</code></p>
<p><code class="literal">PUT /&lt;index&gt;/_create/&lt;_id&gt;</code></p>
<p><code class="literal">POST /&lt;index&gt;/_create/&lt;_id&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-index-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;index&gt;</code>
</span>
</dt>
<dd>
(Required, string) Name of the target index. By default, the index is created
automatically if it doesn’t exist. For more information, see <a class="xref" href="docs-index_.html#index-creation" title="Create indices automatically">Create indices automatically</a>.
</dd>
<dt>
<span class="term">
<code class="literal">&lt;_id&gt;</code>
</span>
</dt>
<dd>
(Optional, string) Unique identifier for the document. Required if you are
using a PUT request. Omit to automatically generate an ID when using a
POST request.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-index-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">if_seq_no</code>
</span>
</dt>
<dd>
(Optional, integer) Only perform the operation if the document has this
sequence number. See <a class="xref" href="docs-index_.html#optimistic-concurrency-control-index" title="Optimistic concurrency control">Optimistic concurrency control</a>.
</dd>
<dt>
<span class="term">
<code class="literal">if_primary_term</code>
</span>
</dt>
<dd>
(Optional, integer) Only perform the operation if the document has
this primary term. See <a class="xref" href="docs-index_.html#optimistic-concurrency-control-index" title="Optimistic concurrency control">Optimistic concurrency control</a>.
</dd>
<dt>
<span class="term">
<code class="literal">op_type</code>
</span>
</dt>
<dd>
(Optional, enum) Set to <code class="literal">create</code> to only index the document
if it does not already exist (<em>put if absent</em>). If a document with the specified
<code class="literal">_id</code> already exists, the indexing operation will fail. Same as using the
<code class="literal">&lt;index&gt;/_create</code> endpoint. Valid values: <code class="literal">index</code>, <code class="literal">create</code>.
If document id is specified, it defaults to <code class="literal">index</code>. Otherwise, it defaults to <code class="literal">create</code>.
</dd>
<dt>
<span class="term">
<code class="literal">pipeline</code>
</span>
</dt>
<dd>
(Optional, string) ID of the pipeline to use to preprocess incoming documents.
</dd>
<dt>
<span class="term">
<code class="literal">refresh</code>
</span>
</dt>
<dd>
(Optional, enum) If <code class="literal">true</code>, Elasticsearch refreshes the affected shards to make this
operation visible to search, if <code class="literal">wait_for</code> then wait for a refresh to make
this operation visible to search, if <code class="literal">false</code> do nothing with refreshes.
Valid values: <code class="literal">true</code>, <code class="literal">false</code>, <code class="literal">wait_for</code>. Default: <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">routing</code>
</span>
</dt>
<dd>
(Optional, string) Target the specified primary shard.
</dd>
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">version</code>
</span>
</dt>
<dd>
(Optional, integer) Explicit version number for concurrency control.
The specified version must match the current version of the document for the
request to succeed.
</dd>
<dt>
<span class="term">
<code class="literal">version_type</code>
</span>
</dt>
<dd>
(Optional, enum) Specific version type: <code class="literal">internal</code>, <code class="literal">external</code>,
<code class="literal">external_gte</code>.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_active_shards</code>
</span>
</dt>
<dd>
<p>(Optional, string) The number of shard copies that must be active before
proceeding with the operation. Set to <code class="literal">all</code> or any positive integer up
to the total number of shards in the index (<code class="literal">number_of_replicas+1</code>).
Default: 1, the primary shard.</p>
<p>See <a class="xref" href="docs-index_.html#index-wait-for-active-shards" title="Active shards">Active shards</a>.</p>
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-index-api-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;field&gt;</code>
</span>
</dt>
<dd>
(Required, string) Request body contains the JSON source for the document
data.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-index-api-response-body"></a>Response body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">_shards</code>
</span>
</dt>
<dd>
Provides information about the replication process of the index operation.
</dd>
<dt>
<span class="term">
<code class="literal">_shards.total</code>
</span>
</dt>
<dd>
Indicates how many shard copies (primary and replica shards) the index operation
should be executed on.
</dd>
<dt>
<span class="term">
<code class="literal">_shards.successful</code>
</span>
</dt>
<dd>
<p>
Indicates the number of shard copies the index operation succeeded on.
When the index operation is successful, <code class="literal">successful</code> is at least 1.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Replica shards might not all be started when an indexing operation
returns successfully—​by default, only the primary is required. Set
<code class="literal">wait_for_active_shards</code> to change this default behavior. See
<a class="xref" href="docs-index_.html#index-wait-for-active-shards" title="Active shards">Active shards</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">_shards.failed</code>
</span>
</dt>
<dd>
An array that contains replication-related errors in the case an index operation
failed on a replica shard. 0 indicates there were no failures.
</dd>
<dt>
<span class="term">
<code class="literal">_index</code>
</span>
</dt>
<dd>
The name of the index the document was added to.
</dd>
<dt>
<span class="term">
<code class="literal">_type</code>
</span>
</dt>
<dd>
The document type. Elasticsearch indices now support a single document type, <code class="literal">_doc</code>.
</dd>
<dt>
<span class="term">
<code class="literal">_id</code>
</span>
</dt>
<dd>
The unique identifier for the added document.
</dd>
<dt>
<span class="term">
<code class="literal">_version</code>
</span>
</dt>
<dd>
The document version. Incremented each time the document is updated.
</dd>
<dt>
<span class="term">
<code class="literal">_seq_no</code>
</span>
</dt>
<dd>
The sequence number assigned to the document for the indexing operation.
Sequence numbers are used to ensure an older version of a document
doesn’t overwrite a newer version. See <a class="xref" href="docs-index_.html#optimistic-concurrency-control-index" title="Optimistic concurrency control">Optimistic concurrency control</a>.
</dd>
<dt>
<span class="term">
<code class="literal">_primary_term</code>
</span>
</dt>
<dd>
The primary term assigned to the document for the indexing operation.
See <a class="xref" href="docs-index_.html#optimistic-concurrency-control-index" title="Optimistic concurrency control">Optimistic concurrency control</a>.
</dd>
<dt>
<span class="term">
<code class="literal">result</code>
</span>
</dt>
<dd>
The result of the indexing operation, <code class="literal">created</code> or <code class="literal">updated</code>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-index-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h3>
</div></div></div>
<p>You can index a new JSON document with the <code class="literal">_doc</code> or <code class="literal">_create</code> resource. Using
<code class="literal">_create</code> guarantees that the document is only indexed if it does not already
exist. To update an existing document, you must use the <code class="literal">_doc</code> resource.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="index-creation"></a>Create indices automatically<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h4>
</div></div></div>
<p>If the specified index does not already exist, by default the index operation
automatically creates it and applies any configured
<a class="xref" href="indices-templates.html" title="Put index template API">index templates</a>. If no mapping exists, the index operation
creates a dynamic mapping.  By default,  new fields and objects are
automatically added to the mapping if needed. For more information about field
mapping, see <a class="xref" href="mapping.html" title="Mapping">mapping</a> and the <a class="xref" href="indices-put-mapping.html" title="Put mapping API">put mapping</a> API.</p>
<p>Automatic index creation is controlled by the <code class="literal">action.auto_create_index</code>
setting. This setting defaults to <code class="literal">true</code>, which allows any index to be created
automatically. You can modify this setting to explicitly allow or block
automatic creation of indices that match specified patterns, or set it to
<code class="literal">false</code> to disable automatic index creation entirely. Specify a
comma-separated list of patterns you want to allow, or prefix each pattern with
<code class="literal">+</code> or <code class="literal">-</code> to indicate whether it should be allowed or blocked.  When a list is
specified, the default behaviour is to disallow.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _cluster/settings
{
    "persistent": {
        "action.auto_create_index": "twitter,index10,-index1*,+ind*" <a id="CO553-1"></a><i class="conum" data-value="1"></i>
    }
}

PUT _cluster/settings
{
    "persistent": {
        "action.auto_create_index": "false" <a id="CO553-2"></a><i class="conum" data-value="2"></i>
    }
}

PUT _cluster/settings
{
    "persistent": {
        "action.auto_create_index": "true" <a id="CO553-3"></a><i class="conum" data-value="3"></i>
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1451.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO553-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Allow auto-creation of indices called <code class="literal">twitter</code> or <code class="literal">index10</code>, block the
creation of indices that match the pattern <code class="literal">index1*</code>, and allow creation of
any other indices that match the <code class="literal">ind*</code> pattern. Patterns are matched in
the order specified.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO553-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Disable automatic index creation entirely.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO553-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>Allow automatic creation of any index. This is the default.</p>
</td>
</tr>
</table>
</div>
<h5>
<a id="operation-type"></a>Put if absent<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>You can force a create operation by using the <code class="literal">_create</code> resource or
setting the <code class="literal">op_type</code> parameter to <em>create</em>. In this case,
the index operation fails if a document with the specified ID
already exists in the index.</p>
<h5>
<a id="_create_document_ids_automatically"></a>Create document IDs automatically<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>If you don’t specify a document ID when using POST, the <code class="literal">op_type</code> is
automatically set to <code class="literal">create</code> and the index operation generates a unique ID
for the document.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_doc/
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1452.console"></div>
<p>The API returns the following result:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
    "_shards" : {
        "total" : 2,
        "failed" : 0,
        "successful" : 2
    },
    "_index" : "twitter",
    "_type" : "_doc",
    "_id" : "W0tpsmIBdwcYyG50zbta",
    "_version" : 1,
    "_seq_no" : 0,
    "_primary_term" : 1,
    "result": "created"
}</pre>
</div>
<h5>
<a id="optimistic-concurrency-control-index"></a>Optimistic concurrency control<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>Index operations can be made conditional and only be performed if the last
modification to the document was assigned the sequence number and primary
term specified by the <code class="literal">if_seq_no</code> and <code class="literal">if_primary_term</code> parameters. If a
mismatch is detected, the operation will result in a <code class="literal">VersionConflictException</code>
and a status code of 409. See <a class="xref" href="optimistic-concurrency-control.html" title="Optimistic concurrency control">Optimistic concurrency control</a> for more details.</p>
<h5>
<a id="index-routing"></a>Routing<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>By default, shard placement — or <code class="literal">routing</code> — is controlled by using a
hash of the document’s id value. For more explicit control, the value
fed into the hash function used by the router can be directly specified
on a per-operation basis using the <code class="literal">routing</code> parameter. For example:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_doc?routing=kimchy
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1453.console"></div>
<p>In this example, the document is routed to a shard based on
the <code class="literal">routing</code> parameter provided: "kimchy".</p>
<p>When setting up explicit mapping, you can also use the <code class="literal">_routing</code> field
to direct the index operation to extract the routing value from the
document itself. This does come at the (very minimal) cost of an
additional document parsing pass. If the <code class="literal">_routing</code> mapping is defined
and set to be <code class="literal">required</code>, the index operation will fail if no routing
value is provided or extracted.</p>
<h5>
<a id="index-distributed"></a>Distributed<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>The index operation is directed to the primary shard based on its route
(see the Routing section above) and performed on the actual node
containing this shard. After the primary shard completes the operation,
if needed, the update is distributed to applicable replicas.</p>
<h5>
<a id="index-wait-for-active-shards"></a>Active shards<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>To improve the resiliency of writes to the system, indexing operations
can be configured to wait for a certain number of active shard copies
before proceeding with the operation. If the requisite number of active
shard copies are not available, then the write operation must wait and
retry, until either the requisite shard copies have started or a timeout
occurs. By default, write operations only wait for the primary shards
to be active before proceeding (i.e. <code class="literal">wait_for_active_shards=1</code>).
This default can be overridden in the index settings dynamically
by setting <code class="literal">index.write.wait_for_active_shards</code>. To alter this behavior
per operation, the <code class="literal">wait_for_active_shards</code> request parameter can be used.</p>
<p>Valid values are <code class="literal">all</code> or any positive integer up to the total number
of configured copies per shard in the index (which is <code class="literal">number_of_replicas+1</code>).
Specifying a negative value or a number greater than the number of
shard copies will throw an error.</p>
<p>For example, suppose we have a cluster of three nodes, <code class="literal">A</code>, <code class="literal">B</code>, and <code class="literal">C</code> and
we create an index <code class="literal">index</code> with the number of replicas set to 3 (resulting in
4 shard copies, one more copy than there are nodes). If we
attempt an indexing operation, by default the operation will only ensure
the primary copy of each shard is available before proceeding. This means
that even if <code class="literal">B</code> and <code class="literal">C</code> went down, and <code class="literal">A</code> hosted the primary shard copies,
the indexing operation would still proceed with only one copy of the data.
If <code class="literal">wait_for_active_shards</code> is set on the request to <code class="literal">3</code> (and all 3 nodes
are up), then the indexing operation will require 3 active shard copies
before proceeding, a requirement which should be met because there are 3
active nodes in the cluster, each one holding a copy of the shard. However,
if we set <code class="literal">wait_for_active_shards</code> to <code class="literal">all</code> (or to <code class="literal">4</code>, which is the same),
the indexing operation will not proceed as we do not have all 4 copies of
each shard active in the index. The operation will timeout
unless a new node is brought up in the cluster to host the fourth copy of
the shard.</p>
<p>It is important to note that this setting greatly reduces the chances of
the write operation not writing to the requisite number of shard copies,
but it does not completely eliminate the possibility, because this check
occurs before the write operation commences. Once the write operation
is underway, it is still possible for replication to fail on any number of
shard copies but still succeed on the primary. The <code class="literal">_shards</code> section of the
write operation’s response reveals the number of shard copies on which
replication succeeded/failed.</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">{
    "_shards" : {
        "total" : 2,
        "failed" : 0,
        "successful" : 2
    }
}</pre>
</div>
<h5>
<a id="index-refresh"></a>Refresh<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>Control when the changes made by this request are visible to search. See
<a class="xref" href="docs-refresh.html" title="?refresh">refresh</a>.</p>
<h5>
<a id="index-noop"></a>Noop updates<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>When updating a document using the index API a new version of the document is
always created even if the document hasn’t changed. If this isn’t acceptable
use the <code class="literal">_update</code> API with <code class="literal">detect_noop</code> set to true. This option isn’t
available on the index API because the index API doesn’t fetch the old source
and isn’t able to compare it against the new source.</p>
<p>There isn’t a hard and fast rule about when noop updates aren’t acceptable.
It’s a combination of lots of factors like how frequently your data source
sends updates that are actually noops and how many queries per second
Elasticsearch runs on the shard receiving the updates.</p>
<h5>
<a id="timeout"></a>Timeout<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>The primary shard assigned to perform the index operation might not be
available when the index operation is executed. Some reasons for this
might be that the primary shard is currently recovering from a gateway
or undergoing relocation. By default, the index operation will wait on
the primary shard to become available for up to 1 minute before failing
and responding with an error. The <code class="literal">timeout</code> parameter can be used to
explicitly specify how long it waits. Here is an example of setting it
to 5 minutes:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT twitter/_doc/1?timeout=5m
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1454.console"></div>
<h5>
<a id="index-versioning"></a>Versioning<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>Each indexed document is given a version number. By default,
internal versioning is used that starts at 1 and increments
with each update, deletes included. Optionally, the version number can be
set to an external value (for example, if maintained in a
database). To enable this functionality, <code class="literal">version_type</code> should be set to
<code class="literal">external</code>. The value provided must be a numeric, long value greater than or equal to 0,
and less than around 9.2e+18.</p>
<p>When using the external version type, the system checks to see if
the version number passed to the index request is greater than the
version of the currently stored document. If true, the document will be
indexed and the new version number used. If the value provided is less
than or equal to the stored document’s version number, a version
conflict will occur and the index operation will fail. For example:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT twitter/_doc/1?version=2&amp;version_type=external
{
    "message" : "elasticsearch now has versioning support, double cool!"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1455.console"></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Versioning is completely real time, and is not affected by the
near real time aspects of search operations. If no version is provided,
then the operation is executed without any version checks.</p>
</div>
</div>
<p>In the previous example, the operation will succeed since the supplied
version of 2 is higher than
the current document version of 1. If the document was already updated
and its version was set to 2 or higher, the indexing command will fail
and result in a conflict (409 http status code).</p>
<p>A nice side effect is that there is no need to maintain strict ordering
of async indexing operations executed as a result of changes to a source
database, as long as version numbers from the source database are used.
Even the simple case of updating the Elasticsearch index using data from
a database is simplified if external versioning is used, as only the
latest version will be used if the index operations arrive out of order for
whatever reason.</p>
<h5>
<a id="index-version-types"></a>Version types<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h5>
<p>In addition to the <code class="literal">external</code> version type, Elasticsearch
also supports other types for specific use cases:</p>
<div class="variablelist">
<a id="_version_types"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">internal</code>
</span>
</dt>
<dd>
Only index the document if the given version is identical to the version
of the stored document.
</dd>
<dt>
<span class="term">
<code class="literal">external</code> or <code class="literal">external_gt</code>
</span>
</dt>
<dd>
Only index the document if the given version is strictly higher
than the version of the stored document <span class="strong strong"><strong>or</strong></span> if there is no existing document. The given
version will be used as the new version and will be stored with the new document. The supplied
version must be a non-negative long number.
</dd>
<dt>
<span class="term">
<code class="literal">external_gte</code>
</span>
</dt>
<dd>
Only index the document if the given version is <span class="strong strong"><strong>equal</strong></span> or higher
than the version of the stored document. If there is no existing document
the operation will succeed as well. The given version will be used as the new version
and will be stored with the new document. The supplied version must be a non-negative long number.
</dd>
</dl>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The <code class="literal">external_gte</code> version type is meant for special use cases and
should be used with care. If used incorrectly, it can result in loss of data.
There is another option, <code class="literal">force</code>, which is deprecated because it can cause
primary and replica shards to diverge.</p>
</div>
</div>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-index-api-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/index_.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Insert a JSON document into the <code class="literal">twitter</code> index with an <code class="literal">_id</code> of 1:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT twitter/_doc/1
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1456.console"></div>
<p>The API returns the following result:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
    "_shards" : {
        "total" : 2,
        "failed" : 0,
        "successful" : 2
    },
    "_index" : "twitter",
    "_type" : "_doc",
    "_id" : "1",
    "_version" : 1,
    "_seq_no" : 0,
    "_primary_term" : 1,
    "result" : "created"
}</pre>
</div>
<p>Use the <code class="literal">_create</code> resource to index a document into the <code class="literal">twitter</code> index if
no document with that ID exists:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT twitter/_create/1
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1457.console"></div>
<p>Set the <code class="literal">op_type</code> parameter to <em>create</em> to index a document into the <code class="literal">twitter</code>
index if no document with that ID exists:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT twitter/_doc/1?op_type=create
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1458.console"></div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="docs-replication.html">« Reading and Writing documents</a>
</span>
<span class="next">
<a href="docs-get.html">Get API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>